home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2000 #1 / Amiga Plus CD - 2000 - No. 1.iso / Tools / Text / Edit / GoldED-Demo / installdata / golded / developer / registry / readme
Encoding:
Text File  |  1999-12-03  |  6.0 KB  |  155 lines
  1. COPYIGHT
  2.  
  3.   ©1999 Dietmar Eilert. All Rights Reserved.
  4.  
  5.   Dietmar Eilert
  6.   Mies-v-d-Rohe-Str.31, 52074 Aachen, Germany
  7.   Phone: +49-(0)179-5987061 German/English
  8.   E-Mail: Dietmar.Eilert@post.rwth-aachen.de
  9.   E-Mail: dietmar_eilert@yahoo.de (alternative address)
  10.   WWW:    http://members.tripod.com/golded
  11.   Mirror: http://members.xoom.com/golded
  12.  
  13. CONTENTS
  14.  
  15.   This is a description of the physical data format used  for  the  registry,
  16.   preset  files,  sequences,  etc. A description of the logical format can be
  17.   found in the "registry.h" file. Please  note  that  the  information  given
  18.   there describes the current state only; future versions may use a different
  19.   logical format.  The  physical  file  format  described  in  this  text  is
  20.   guaranteed to stay the same.
  21.  
  22. REGISTRY
  23.  
  24.   The global  configuration  of  GoldED  Studio  5  (including  the  list  of
  25.   filetypes)  is  saved  to the registry file "golded:etc/registry/registry".
  26.   The registry is loaded during startup. Presets referenced by  the  registry
  27.   are  stored in the directory "golded:etc/registry/presets". These files use
  28.   the same file format.
  29.  
  30. CONFIGURATION FORMAT
  31.  
  32.   An object-oriented tree-style format is used for configuration data.  Every
  33.   configurable  option  in  the editor is described by an "object" structure.
  34.   This is how GoldED internally represents objects when loaded into RAM:
  35.  
  36.   struct Object {
  37.  
  38.       struct Node Node;
  39.  
  40.       UWORD                 ID;
  41.       UWORD                 Type;
  42.       struct Class         *Class;
  43.  
  44.       union {
  45.  
  46.           ULONG             Number;
  47.           UBYTE            *String;
  48.           struct List      *List;
  49.           APTR              Data;
  50.  
  51.       } Value;
  52.   };
  53.  
  54.   /* object types (bit 0-2) */
  55.  
  56.   #define OBJECT_TYPE_NUMBER     1
  57.   #define OBJECT_TYPE_STRING     2
  58.   #define OBJECT_TYPE_LIST       3
  59.   #define OBJECT_TYPE_DATA       4
  60.   #define OBJECT_TYPE_NAMED      8
  61.  
  62.   /* special object ID
  63.  
  64.   #define OBJECT_LOCKED ((UWORD)~0)
  65.  
  66.   NODE:
  67.  
  68.   Objects are linked together  via  the  Node  field  and  form  large  trees
  69.   (objects  of  the  type  OBJECT_TYPE_LIST  are  the root of branches). Some
  70.   objects are named (see below): a pointer to the object's name is stored  in
  71.   object->Node.ln_Name. The node's ln_Pri field is used to coordinate access:
  72.   it is set to OBJECT_LOCKED if an object is currently in use and may not  be
  73.   deleted or modified (except by the owner of the object).
  74.  
  75.   ID:
  76.  
  77.   ID is  the  object  ID.  Most  objects  have  a  unique  ID.  For  example,
  78.   OBJECT_GLOBAL_FINDTEXT  refers to the object that is used to store the last
  79.   find  string.  Current  ID  definitions  can   be   found   in   the   file
  80.   "include/registry.h".
  81.  
  82.   TYPE:
  83.  
  84.   The  object  type.  Four  basic  types  are   available:   Number   objects
  85.   (OBJECT_TYPE_NUMBER)  can  store  a  single number. The number is stored in
  86.   <object->Value.Number>. They can be used  to  store  boolean  values,  too.
  87.   String  objects  (OBJECT_TYPE_STRING)  can  store  strings.  A pointer to a
  88.   0-terminated string is stored in <object->Value.String>. The string pointer
  89.   may   be   NULL  to  indicate  that  the  string  is  empty.  Data  objects
  90.   (OBJECT_TYPE_DATA) can store arbitrary memory  blocks.  A  pointer  to  the
  91.   memory block is stored in <object->Value.Data>. The block size is stored in
  92.   four bytes before the memory block similar to how  AllocVec()  stores  size
  93.   information.  List  objects  (OBJECT_TYPE_LIST)  can  store object lists. A
  94.   non-NULL pointer to the list structure is stored  in  <object->Value.List>.
  95.   The  list's  lh_Head  field  points  to the first child object. The list of
  96.   children may  contain  further  OBJECT_TYPE_LIST  objects  with  their  own
  97.   sublists. There are no nesting limits (recursive programming required).
  98.  
  99.   Some objects are named. Named objects have the OBJECT_TYPE_NAMED bit set (a
  100.   pointer  to the name is stored in object->Node.ln_Name as mentioned above).
  101.   You have to mask the object type with 0x7 to filter this flag when checking
  102.   the type:
  103.  
  104.   type = object->Type & 0x7
  105.  
  106.   CLASS:
  107.  
  108.   A pointer to the "class"  that  is  reponsible  for  object  handling,  ie.
  109.   creation, disposal, etc.
  110.  
  111.  
  112. FILE FORMAT
  113.  
  114.   The following paragraph describes how the run-time format (linked trees  of
  115.   objects)  is saved to disk: this is a description of the format used by the
  116.   commercial version to save the registry, configuration presets and recorded
  117.   sequences.
  118.  
  119.   The first four bytes of every data file are  "OOP"  (0-terminated  string).
  120.   The  data  of  a  single object, the "root object", follows: every OOP file
  121.   consists of a single root  object  without  successor.  However,  the  root
  122.   object usually is a OBJECT_TYPE_LIST object: It has no successor but it may
  123.   have an unlimited number of children. The children are stored  sequentially
  124.   directly after the root object.
  125.  
  126.   The physical format of how the object is stored in the file depends on  the
  127.   object  type but the basic structure is independend of the object type: The
  128.   first two bytes (UWORD) contain the object type and the  object  ID.  These
  129.   values  are combined to a "fat ID" to save disk space. The object ID can be
  130.   found in bit 0-10, the type can be found in bit 11-15 (ID = fatID  &  2047,
  131.   Type = fatID / 2048). Some objects are named and have the OBJECT_TYPE_NAMED
  132.   bit set (in <type>). The name (if the OBJECT_TYPE_NAMED bit is set) follows
  133.   immediately  after  the  fat ID as a 0-terminated string. The object's data
  134.   follows after the name; the format depends on the object type:
  135.  
  136.   OBJECT_TYPE_NUMBER
  137.  
  138.      The object's numerical value is stored in the next four bytes (LONG).
  139.  
  140.   OBJECT_TYPE_STRING
  141.  
  142.      A 0-terminated byte sequence
  143.  
  144.   OBJECT_TYPE_DATA
  145.  
  146.      The block size stored in the next four bytes (ULONG) followed by the
  147.      specified number of raw bytes.
  148.  
  149.   OBJECT_TYPE_LIST
  150.  
  151.      The number of children is stored in the next four bytes (ULONG) followed
  152.      by the specified number of child objects. Child objects are saved in the
  153.      same format as root objects: fat ID (type/ID) followed by the  name  (if
  154.      named) followed by the object data.
  155.